# 音乐与音频库

```{admonition} 本文引用的文件
:class: note

- `modmusic.c`
- `modmusictunes.c`
- `modcodec.c`
- `modxunfeiAI.c`
- [audio.rst](../../../../products/mpython/library/mPython/audio.rst)
- [musicbox.rst](../../../../products/mpython/classic/musicbox.rst)
- `audio_play.py`
- `PlayMusic.py`
```

## 产品概述
本模块面向K12创客教育与嵌入式音频应用，提供三类能力：
- music模块（兼容micro:bit）：基于MCPWM输出方波驱动蜂鸣器或简易扬声器，支持音符序列、内置曲库、节拍控制等。
- audio模块（ESP32）：基于音频编解码与I2S/Codec的播放与录音能力，支持本地/网络MP3/WAV播放、音量控制、录音到WAV、以及讯飞在线TTS/IAT相关接口。
- 讯飞语音听写（IAT）：通过WebSocket与HTTP方式对接讯飞开放平台，实现语音转文字与文本转语音。

适用场景包括：课堂互动音效、简单乐器、语音交互原型、离线/在线语音识别与合成等。

## 核心业务流程
- 音乐播放流程（music）
  - 初始化内部状态与PWM资源
  - 解析音符字符串或内置曲目常量
  - 按BPM与拍号计算时值，异步逐音播放
  - 支持循环、等待完成、停止
- 音频播放/录音流程（audio）
  - 初始化播放器/录音器
  - 播放本地或网络音频（MP3/WAV），查询状态，控制暂停/恢复/停止
  - 录音为WAV文件，读取响度，释放资源
- 讯飞IAT/TTS流程
  - 配置鉴权参数（app_id/api_key/api_secret）
  - WebSocket建立连接并发送音频流（IAT）
  - 调用在线服务返回识别结果；TTS将文本转为语音并播放

```text
sequenceDiagram
participant App as "用户程序"
participant Music as "music模块"
participant PWM as "MCPWM硬件"
App->>Music : play(音符列表/内置曲名, wait, loop)
Music->>Music : 解析音符/设置节拍
Music->>PWM : 设置频率/占空比
PWM-->>Music : 播放完成回调
Music-->>App : 完成/继续下一音
```

**图表来源**
- `modmusic.c:46-54`
- `modmusic.c:92-148`
- `modmusic.c:163-273`

**章节来源**
- `modmusic.c:46-54`
- `modmusic.c:92-148`
- `modmusic.c:163-273`

## 功能模块清单
- music模块（兼容micro:bit）
  - 播放音符/曲谱：play(tune, pin=16, wait=True, loop=False)
  - 播放指定频率音调：pitch(frequency, duration=-1, pin=16, wait=True)
  - 停止播放：stop(pin=None)
  - 节拍控制：set_tempo(ticks=4, bpm=120)、get_tempo()
  - 重置：reset()
  - 内置曲库常量：DADADADUM、ENTERTAINER、PRELUDE、ODE、NYAN、RINGTONE、FUNK、BLUES、BIRTHDAY、WEDDING、FUNERAL、PUNCHLINE、PYTHON、BADDY、CHASE、BA_DING、WAWAWAWAA、JUMP_UP、JUMP_DOWN、POWER_UP、POWER_DOWN、GE_CHANG_ZU_GUO、DONG_FANG_HONG、CAI_YUN_ZHUI_YUE、ZOU_JIN_XIN_SHI_DAI、MO_LI_HUA、YI_MENG_SHAN_XIAO_DIAO
- audio模块（ESP32）
  - 播放：player_init()、play(url)、pause()/resume()/stop()、set_volume(vol)、player_status()、player_deinit()
  - 录音：recorder_init()、record(file_name, record_time=5)、loudness()、recorder_deinit()
  - 讯飞在线TTS：xunfei_tts_config(config)、xunfei_tts(text)
  - 讯飞在线IAT：xunfei_iat_config(config)、xunfei_iat_record(rec_time)、xunfei_iat()
- 讯飞语音听写（IAT）独立模块
  - xunfeiAI.xunfei_iat_init(app_id, api_key, api_secret, text, language="zh_cn")
  - xunfeiAI.xunfei_tts()
  - xunfeiAI.xunfei_iat(url)

验收要点
- music模块可播放单音与多音序列，支持循环与等待模式，能正确解析音符与时值。
- audio模块可初始化并播放本地/网络音频，支持暂停/恢复/停止与音量调节；录音生成WAV并可读响度。
- IAT/TTS需联网并在讯飞平台完成鉴权配置后，能成功发起请求并获取结果或播放语音。

**章节来源**
- `modmusic.c:275-456`
- `modmusic.c:459-522`
- `modmusictunes.c:44-237`
- `modcodec.c:47-128`
- `modcodec.c:131-183`
- `modcodec.c:186-398`
- `modxunfeiAI.c:126-223`

## 数据与状态
- music模块
  - 运行时状态机：空闲/下一音/发音间隙，用于非阻塞播放与自动切音
  - 节拍参数：BPM与每拍ticks，影响音符时长
  - 音符解析：支持升降号、八度、时值后缀，默认中音区与四分音符
  - 引脚管理：动态申请/释放MCPWM输出引脚，避免冲突
- audio模块
  - 播放器状态：运行/暂停/空闲，供status查询
  - 录音参数：采样率、位深、声道数（WAV）
  - 网络播放：URL解析、HTTP下载与解码缓冲
- 讯飞IAT/TTS
  - 鉴权信息：app_id、api_key、api_secret
  - 协议：WebSocket握手签名（HMAC-SHA256 + Base64）、时间戳、Host头
  - 数据流：音频流上传（IAT）、文本下发（TTS）

```text
flowchart TD
Start(["开始"]) --> Init["初始化music状态<br/>设置BPM/ticks"]
Init --> Parse{"输入是单音还是序列?"}
Parse --> |单音| PlayOne["设置频率/占空比"]
Parse --> |序列| LoopNotes["遍历音符列表"]
PlayOne --> Wait{"wait=True?"}
LoopNotes --> Wait
Wait --> |是| Block["等待播放完成"]
Wait --> |否| Return["立即返回"]
Block --> End(["结束"])
Return --> End
```

**图表来源**
- `modmusic.c:92-148`
- `modmusic.c:163-273`
- `modmusic.c:312-376`

**章节来源**
- `modmusic.c:62-86`
- `modmusic.c:92-148`
- `modmusic.c:163-273`
- `modcodec.c:47-128`
- `modcodec.c:131-183`
- `modxunfeiAI.c:62-75`
- `modxunfeiAI.c:79-119`

## 关键约束与边界
- 硬件与平台
  - music模块使用ESP32 MCPWM输出，默认引脚16，需确保GPIO有效且未被占用
  - audio模块依赖I2S与Codec（如ES8388），需在无DAC构建时传入I2C对象进行初始化
  - ESP32-S3固件未包含modcodec与modxunfeiAI，audio与IAT能力以ESP32为主
- 音频格式与大小
  - 播放支持wav/mp3；本地大文件受文件系统与RAM限制，建议小体积音频
  - 录音为WAV（8kHz、16bit、单声道），时长受存储容量限制
- 网络与服务
  - 网络播放需先连接WiFi
  - 讯飞IAT/TTS需联网并完成鉴权配置；IAT最长约60秒
- 并发与阻塞
  - music.play支持wait/loop控制阻塞行为；pitch支持duration延时停止
  - 音频播放状态可通过player_status查询，避免重复操作

最佳实践
- 使用music.play(..., wait=False)在需要与其他任务并行时使用
- 播放结束后调用stop或等待自然结束，避免引脚占用
- 网络播放前检查WiFi连接与URL有效性
- 讯飞API使用前务必配置鉴权参数，并确保网络可达

**章节来源**
- `modmusic.c:312-376`
- `modcodec.c:47-66`
- `modcodec.c:76-128`
- [audio.rst:32-78](../../../../products/mpython/library/mPython/audio.rst)
- [audio.rst:83-113](../../../../products/mpython/library/mPython/audio.rst)
- `modxunfeiAI.c:126-201`

## 附录：示例与参考路径
- 音乐盒示例（按键切换内置曲目）
  - 参考：[musicbox.rst](../../../../products/mpython/classic/musicbox.rst)
- 音频播放示例（本地/网络MP3）
  - 参考：`audio_play.py`
- 蜂鸣器播放旋律示例
  - 参考：`PlayMusic.py`